Extended String Support with CHAR Arrays

VectorScript also supports a specialized set of functionality when using arrays of the CHAR data type. This functionality with static or dynamic arrays of the CHAR type provides you with a means of handling extended strings up to 32,767 characters long within your scripts.

Arrays of type CHAR can be used in place of the STRING data type in certain operations within VectorScript. The following sections provide details on operations supporting CHAR arrays and STRINGs in VectorScript.

Assignments Between STRING Values and CHAR Arrays

Both static CHAR arrays (ARRAY OF CHAR) and dynamic CHAR arrays (DYNARRAY OF CHAR) can be used in place of STRING values when assigning to or retrieving from a STRING variable.

When using either static or dynamic CHAR arrays to assign a value to a STRING variable, if the array length exceeds 255 characters, the first 255 characters will be copied into the string variable, and the remaining characters in the array will be dropped. Values of less than 255 characters will be completely copied into the STRING variable.

Assigning values from a STRING variable or constant to a static CHAR array works in a similar fashion. If the CHAR array has a length less than the length of the STRING value to be assigned, the value will be truncated to fit the array. For instance:

 

PROCEDURE Example_43;

VAR

Part_name: STRING;

NameArray: ARRAY[1..16] OF CHAR;

BEGIN

part_name:= 'Acme Left-handed Smoke Shifter';

NameArray:=part_name;

END;

Run(Example_43);

In the example, the STRING value assigned to the variable part_name would be truncated to

Acme Left-handed

when assigned to the array. When using static CHAR arrays to handle STRING values, be sure to declare the size of the array to accommodate the longest STRING value expected to be stored within the array.

In contrast to static CHAR arrays, dynamic CHAR arrays will automatically size to the length of the STRING value being assigned to the array. For example:

 

PROCEDURE Example_44;

VAR

sampleString: STRING;

mytext: DYNARRAY[] OF CHAR;

BEGIN

sampleString:= 'VectorScript now handles lots of text';

mytext:= sampleString;

END;

Run(Example_44);

If the array mytext was declared but not previously used, the assignment would size the array length to 36, and the array would contain the string

VectorScript now handles lots of text

If mytext had been previously assigned a value, the assignment would resize the array to a length of 36 and assign the STRING value to the array. The values previously held in the array would be lost.

Retrieving or Assigning Strings to Text Objects

VectorScript allows STRING values greater than 255 characters long in text objects to be set or retrieved via CHAR arrays. The VectorScript API functions GetText() and SetText() support the use of a CHAR array in place of a STRING value.

To set or retrieve the text string, use the name of the CHAR array (without brackets) in place of the STRING parameter or variable. For example:

 

PROCEDURE Example_45;

VAR

h : HANDLE;

theText : STRING;

textArray : DYNARRAY[] OF CHAR;

BEGIN

h:=FSActLayer;

theText:= GetText(h);

CreateText(theText);

END;

Run(Example_45);

In the example, you would be limited to returning the first 255 characters of the text string. By using a dynamic array:

 

PROCEDURE Example_45;

VAR

h : HANDLE;

theText : STRING;

textArray : DYNARRAY[] OF CHAR;

BEGIN

h:=FSActLayer;

textArray:= GetText(h);

CreateText(textArray);

END;

Run(Example_45);

You can retrieve the entire text string and store it in the dynamic array. The entire text string can then be used in other operations.

Retrieving or Assigning Strings to Record Fields

VectorScript also allows you to set and retrieve STRING values greater than 255 characters long contained in record fields via the use of CHAR arrays. The VectorScript API functions GetRField() and SetRField() support the use of a CHAR array in place of a STRING value.

To set or retrieve the record field string, use the name of the CHAR array (without brackets) in place of the STRING parameter or variable. For example:

 

PROCEDURE E xample_46;

VAR

theText : STRING;

longtext : ARRAY[1..512] OF CHAR;

BEGIN

theText:= GetRField(FSActLayer,'Boring Info','Boring Notes');

CreateText(theText);

END;

Run(Example_46);

In the example, using a STRING variable would be limited to retrieving only the first 255 characters of the text string stored within the field. By using a CHAR array:

 

PROCEDURE Example_46;

VAR

theText : STRING;

longtext : ARRAY[1..512] OF CHAR;

BEGIN

longtext:= GetRField(FSActLayer,'Boring Info','Boring Notes');

CreateText(textArray);

END;

Run(Example_46);

In the example, up to 512 characters of text from the field can be retrieved and stored in the array. Alternately, the dynamic array could be sized to support whatever amount of text might be found in the record field (up to 32K of text).